Development setup

Development is done in Eclipse Mars for RCP and RAP Developers. Please work through this guide to correctly set up your development environment.

Eclipse plugins

Required Eclipse plugins are:

• Palladio (Update Site: https://sdqweb.ipd.kit.edu/eclipse/palladiosimulator/nightly/)
• JaMoPP, use the trunk update site http://update.jamopp.org/trunk
• PCM for Vitruvius, as it can be checked out (SVN) from https://svnserver.informatik.kit.edu/i43/svn/code/Palladio/Core/branches/PCM_for_Vitruvius (Credentials: anonymous:anonymous). Import it into your Eclipse workspace.
• SoMoX based on JaMoPP, as it can be checked out (SVN) from https://svnserver.informatik.kit.edu/i43/svn/code/SoMoX/Core/branches/SoMoXWithJaMoPP/ (Credentials: anonymous:anonymous).
  • import all SoMoX projects into your Eclipse workspace (consider using a Working Set to group them). Don’t check “search for nested projects” when importing, but only import the projects at the top level.
  • Close the projects org.somox.metrics.dsl.tests and org.somox.metrics.tests
• The PCM Element Source Statement Links Extractor for SoMoX, as it can be checked out (SVN) from https://svnserver.informatik.kit.edu/i43/svn/code/SoMoX/Addons/PCM Source Statement Links Extractor/ (Credentials: anonymous:anonymous). Import it into your Eclipse workspace.
• Checkstyle
• UMLet (either as Eclipse plugin or as standalone)

Building & Dependency Management

The project is built using Gradle 2.10. It can be downloaded here. Ubuntu users can use this PPA.

We use the default commands: gradle build (or simply gradle) to test and build, gradle test to only run tests. Run gradle tasks to see all available tasks.

Importing the Projects

Please import the root project through Buildship into Eclipse. Make sure to select “Specific Gradle version: 2.10”. This will import all subprojects as well:

Please execute gradle now to set up all required files. You can do so by double-clicking on the “Beagle” project in the “Gradle Tasks” view.

Documentation

Parts of the documentation are written in LaTeX using LyX.

Installation

In order to render PDFs, the following steps need to be performed.

Ubuntu users can try to run the deployment install script at buildSrc/src/deploy/bash/Install Doc.sh, which will execute all installation steps detailed below. Please note thatwhile the script offers great convenience, it was written to be used on a continuous integration server and might hence make settings that are not optimal for a private computer.

You’ll obviously first need to install LyX and LaTeX.

Install the SDQ Template

• Download the SDQ thesis template and install it according to your LaTeX distribution.

  • On Ubuntu:

    • copy the unzipped folder’s contents to /usr/share/texmf/tex/latex/sdqthesis. For example:

      sudo cp -r Ausarbeitungs-Vorlage_SDQ_2014 /usr/share/texmf/tex/latex/sdqthesis
      

    • run sudo texhash

  • On Windows (with MiKTeX):

    • copy the unzipped folder’s contents to your local texmf folder. If you don’t have one yet, create one (for example C:\Users\[User]\texmf) and add it under Roots in the MiKTeX settings. Given [texmf] is your local texmf folder, the contents must be copied into [texmf]\tex\latex\sdqthesis.
    • Launch “MiKTeX Settings” and hit “Refresh FNDB”

  • You may remove the files thesis.tex and thesis.bib as well as the subfolder sections.

• Download the KIT LaTeX templates and install them to your LaTeX distribution.

  • unzip the zip file’s inner zip files.

  • On Ubuntu:

  • copy the contents of KITbase/tex/latex/KIT to /usr/share/texmf/tex/latex/KITBase and the contents of KITbeamer/tex/latex/KIT to /usr/share/texmf/tex/latex/KITBeamer. For example:

    sudo cp -r KITbase/tex/latex/KIT /usr/share/texmf/tex/latex/KITBase
    sudo cp -r KITbeamer/tex/latex/KIT /usr/share/texmf/tex/latex/KITBeamer
    

  • run sudo texhash

  • On Windows (with MiKTeX):

  • copy the contents of KITbase/tex/latex/KIT and KITbeamer/tex/latex/KIT to [texmf]\tex\latex\KIT where [texmf] is your local texmf folder, as explained above.
  • Launch “MiKTeX Settings” and hit “Refresh FNDB”

• Install the LyX layout files Documentation/Dependencies/sqthesis.layout and Documentation/Dependencies/KIT-Beamer.layout.

  • copy the file to your personal layout folder (Ubuntu: ~/.lyx/layouts, Windows: C:\Users\[User]\AppData\Roaming\LyX2.1\layouts)
  • Open LyX and run “Tools -> Reconfigure”
  • Restart LyX to use the template

Install Required Packages

A (small!) subset of the required LaTeX packages are:

• KOMAscript book (scrbook)
• Default packages like inputenc, fontenc, etc.
• Linux Libertine Font (libertine and newtxmath)
• Adobe Source Sans Pro Font (sourcesanspro)
• Bera Mono Font (beramono)
• Microtype (microtype)
• Enumitem (enumitem)
• Break citations (breakcites)
• xindy (xindy)
• Arial (uarial)

If you care for the full list, look it up yourself in sdqthesis.cls, and the KIT template .sty files.

Ubuntu

Most required packages can be installed by installing thetexlive-latex-base, texlive-latex-recommended, texlive-latex-extra, texlive-fonts-extra, xindy, texlive-bibtex-extra and texlive-lang-german debian packages. However, uarial is not open source and must thus be downloaded and installed in an extra step. Run these commands:

sudo apt-get install texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-fonts-extra texlive-lang-german texlive-bibtex-extra xindy
wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts
sudo texlua install-getnonfreefonts
sudo getnonfreefonts-sys arial-urw
rm install-getnonfreefonts

Windows

On Windows, you’ll likely use MiKTeX, which will install automatically all required packages automatically. However, you need to install Perl: ActivePerl. Make sure the checkbox “Add Perl to PATH”, which appears during the installation process, is checked.

Install UMLet

• Install the UMLet standalone. Extract the zip file and move it to C:\Program Files (x86)\Umlet\Umlet.exe (Windows) or /opt/Umlet/ (Linux). (If you want to put it somewhere else, you have to adapt UmletRenderTask.goovy in the Documentation project’s buildSrc project.) UMLet is required to build the documentation.
• If you like to use UMLet as eclipse plugin, you can install this as well. It makes editing the diagrams easier.

Spell checking

You may need to set the language in Tools -> Settings -> Language Settings -> Language to en to get English spell checking.

Markdown

Other parts are written in plain Markdown. The Eclipse GitHub Flavored Markdown viewer plugin for Eclipse helps writing it. (*Hint:* Don’t give the plugin your GitHub credentials. Create a personal access token and change the API URL in the plugin’s settings: https://api.github.com/?access_token=PERSONAL_ACCESS_TOKEN)

Continuous Integration

Beagle uses Travis, a continuous integration service. It tests Pull Requests as well as all branches in the repository whenever changes occur.

You can enable Travis for your repository, too. This allows you to have automated tests for all your commits. It further generates all documentation documents for new commits. This is quite handy for pull requests, as you can simply post a link to the rendered file, making the reviewing process a whole lot easier.

To activate Travis:

Get GitHub Personal Access Token

• Go to your GitHub personal access token settings page and create a new token. Only allowing access to the repo scope is sufficient.
• temporary save the token somewhere, e.g. in your clipboard

Activate Travis

• Go to Travis and sign in
• Activate Travis for your fork of Beagle
• Go to the settings page for Beagle on Travis and create a new Environment Variable called GH_TOKEN. Paste the personal access token you created as value. Leave the “show in log” switch OFF!

Done!